redocly logoAPI docs by Redocly

MiCamp Solutions API v2 (2.0.0)

Welcome to the MiCamp Solutions gateway JSON API.

You can use our API endpoints to easily and securely charge and credit transactions.

To use the MiCamp Solutions API, you must have a merchant account and source key from the MiCamp Solutions gateway.

To create a source key in the gateway, navigate to Control Panel > Source Management > Create Key.

API Base URIs:

  • Production API base URI:

    https://api.micampblue.com/api/v2/

  • Sandbox API base URI:

    https://api.sandbox.micampblue.com/api/v2/

Please use the User-Agent header to identify your software, so requests coming from your integration can be traced.

Charges

Charge

Creates a new authorization / charge. For credit cards, by default, the authorization will be captured into the current batch.

A charge can be from one of the following types of sources:

  • Credit Card: This requires passing fields with credit card data.
  • DAF Card: This requires passing fields with DAF card data.
  • Credit Card Magstripe: This requires passing magstripe data from a swiped credit card.
  • Check / ACH
  • Source: This includes charging based on a previous transaction, a stored payment method, a token, or a nonce.
  • Digital Wallet: An encrypted token containing payment data from a digital wallet provider.

For check transactions, this request requires the Check Charge permission on the source key. For CC transactions, if capture is false, it requires the Auth Only permission, otherwise, it requires the Charge permission.

Authorizations:
BasicAuthentication
Request Body schema: application/json
One of
amount
required
number [ 0.01 .. 20000000 ]

Transaction amount in USD.

If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could be different than the amount submitted in this field. The revised amounts will be returned in the response.

The /surcharge endpoints can be used to check the surcharge before processing. The surcharge will also be returned by the Hosted Tokenization library.

card
required
string [ 14 .. 16 ] characters ^\d+$

Card number
expiry_month
required
integer [ 1 .. 12 ]

Card expiration month. If using a card token, send any valid month.

expiry_year
required
integer [ 2020 .. 9999 ]

Card expiration year. If using a card token, send any valid year.

object (AmountDetails)

Breakdown of the amount. These fields do not affect the actual transaction amount and are for reporting and Level 3 only.

name
string <= 255 characters

Name on payment method (credit card or check).

object

Additional optional transaction details.

Array of objects (Item) non-empty

Line item details for Level 3 data.

The data will not be checked for accuracy, e.g. if the totals add up correctly.

To qualify for Level 3, the line item amounts must match the transaction amounts.

The following fields are required for Level 3 data:

  • sku,
  • description,
  • cost,
  • quantity,
  • tax_rate or tax_amount,
  • commodity_code
object (Address)
object

For level 3, the country must be in ISO 3166-1 alpha-2 format (2 letter code) and the zip code format must match the country.

object (CustomFields)
ignore_duplicates
boolean
Default: false

Determines whether to override any duplicate transactions detection.

object
object (TransactionFlags)

These flags provide more details about the transaction. Although they are optional, is recommended they be sent, to ensure optimal approval rates.

avs_address
string <= 255 characters

Billing address for the card.
avs_zip
string <= 50 characters

Billing zip code for the card.

While not required, this field should be populated for fraud prevention and to obtain the best rate for E-commerce credit card transactions.

cvv2
string [ 3 .. 4 ] characters ^\d+$

Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code on the front of the card. For other card brands, this is the 3 digit code on the back.

While not required, this field should be populated for fraud prevention.

object

Data for 3D-Secure (Verified by Visa, MasterCard SecureCode, Amex SafeKey, Discover ProtectBuy). These values come from a 3rd party 3D-Secure provider.

Note: 3D-Secure is only applicable for e-Commerce merchants. Only 3D-Secure version 2 is supported.

capture
boolean
Default: true

Whether to capture the authorization into the current batch.

save_card
boolean
Default: false

If set to true and the transaction has been approved, the system will issue a token for future use.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 0.01,
  • "amount_details": {
    },
  • "name": "string",
  • "transaction_details": {
    },
  • "line_items": [
    ],
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "custom_fields": {
    },
  • "ignore_duplicates": false,
  • "customer": {
    },
  • "transaction_flags": {
    },
  • "avs_address": "string",
  • "avs_zip": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "cvv2": "stri",
  • "3d_secure": {
    },
  • "card": "stringstringst",
  • "capture": true,
  • "save_card": false
}

Response samples

Content type
application/json
Example
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "auth_amount": 0,
  • "auth_code": "string",
  • "reference_number": 1,
  • "transaction": {
    },
  • "avs_result": "string",
  • "avs_result_code": "YYY",
  • "cvv2_result": "string",
  • "cvv2_result_code": "M",
  • "card_type": "Visa",
  • "last_4": "string",
  • "card_ref": "string"
}

Terminal Charge

Authorizations:
BasicAuthentication
Request Body schema: application/json
amount
required
number [ 0.01 .. 20000000 ]

Transaction amount in USD.

If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could be different than the amount submitted in this field. The revised amounts will be returned in the response.

The /surcharge endpoints can be used to check the surcharge before processing. The surcharge will also be returned by the Hosted Tokenization library.

terminal_id
required
string non-empty

The serial number of the terminal. This must match a terminal that is boarded in the gateway.

object (AmountDetails)

Breakdown of the amount. These fields do not affect the actual transaction amount and are for reporting and Level 3 only.

name
string <= 255 characters

Name on payment method (credit card or check).

object

Additional optional transaction details.

Array of objects (Item) non-empty

Line item details for Level 3 data.

The data will not be checked for accuracy, e.g. if the totals add up correctly.

To qualify for Level 3, the line item amounts must match the transaction amounts.

The following fields are required for Level 3 data:

  • sku,
  • description,
  • cost,
  • quantity,
  • tax_rate or tax_amount,
  • commodity_code
object (Address)
object

For level 3, the country must be in ISO 3166-1 alpha-2 format (2 letter code) and the zip code format must match the country.

object (CustomFields)
ignore_duplicates
boolean
Default: false

Determines whether to override any duplicate transactions detection.

object
source
string <= 26 characters (tkn|ref|pm)-[A-Za-z0-9]+

The source to charge. This can be a token, a payment method or the reference number of a previous transaction. If this field is not sent, the terminal will prompt for a card.

The appropriate prefix must be used:

  • Reference number: ref-
  • Payment method ID: pm-
  • Token: tkn-

By default, a source charge sent without an expiration date will use the expiration date saved with the source. If an expiration date is sent, it will override the saved expiration date.

AVS fields will be automatically populated when using a payment method source unless overridden in the request.

save_card
boolean
Default: false

If set to true and the transaction has been approved, the system will issue a token for future use.

Responses

Request samples

Content type
application/json
{
  • "amount": 0.01,
  • "amount_details": {
    },
  • "name": "string",
  • "transaction_details": {
    },
  • "line_items": [
    ],
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "custom_fields": {
    },
  • "ignore_duplicates": false,
  • "customer": {
    },
  • "terminal_id": "string",
  • "source": "string",
  • "save_card": false
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "auth_amount": 0,
  • "auth_code": "string",
  • "reference_number": 1,
  • "transaction": {
    },
  • "avs_result": "string",
  • "avs_result_code": "YYY",
  • "cvv2_result": "string",
  • "cvv2_result_code": "M",
  • "card_type": "Visa",
  • "last_4": "string",
  • "card_ref": "string"
}

Capture

Capture an authorization into the current batch. If the authorization is already captured, this will still return a successful response.

Only applicable to credit card authorizations.

Not supported for terminal transactions.

This request requires the Capture permission on the source key.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the authorization to capture.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "auth_amount": 0,
  • "auth_code": "string"
}

Adjust

Adjust the amount or details of a previous unsettled transaction.

This endpoint requires that the source key have a pin.

The amount of ACH and Terminal transactions cannot be adjusted, and will return an error if a different amount is sent.

If the original transaction had amount details and this request changes the amount, the amount_details must be resent. If only details are being adjusted and not the amount, the amount field can be omitted.

This request requires the Adjust permission on the source key.

TSYS only supports adjusts on transactions using US or Canadian cards. International cards must use refunds after the transaction has settled.

Adjusting a transaction to a higher amount is only permitted by the card brands in specific scenarios. It is the the responsibility of the merchant to enforce this.

A transaction can only be adjusted once.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the transaction to adjust.

amount
number [ 0.01 .. 20000000 ]

Amount to adjust the original transaction to.

object (BaseTransactionCustomer)
object

Additional optional transaction details.

object (AmountDetails)

Breakdown of the amount. These fields do not affect the actual transaction amount and are for reporting and Level 3 only.

object (Address)
object (Address)
object (CustomFields)
Array of objects (Item) non-empty

Line item details for Level 3 data.

The data will not be checked for accuracy, e.g. if the totals add up correctly.

To qualify for Level 3, the line item amounts must match the transaction amounts.

The new data will replace the old data.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1,
  • "amount": 0.01,
  • "customer": {
    },
  • "transaction_details": {
    },
  • "amount_details": {
    },
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "custom_fields": {
    },
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "auth_amount": 0,
  • "auth_code": "string"
}

Adjust and capture

Adjust the amount or details of a previous unsettled transaction, and captures it into the batch.

This endpoint requires that the source key have a pin.

This endpoint only applies to credit card transactions, and will return an error for ACH transactions.

If the original transaction had amount details and this request changes the amount, the amount_details must be resent. If only details are being adjusted and not the amount, the amount field can be omitted.

This request requires the Capture permission on the source key. If the amount is adjusted, the request will require Adjust permission as well.

TSYS only supports adjusts on transactions using US or Canadian cards. International cards must use refunds.

Adjusting a transaction should only be done in a compliant manner and is the responsibility of the merchant.

A transaction can only be adjusted once.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the transaction to adjust.

amount
number [ 0.01 .. 20000000 ]

Amount to adjust the original transaction to.

object (BaseTransactionCustomer)
object

Additional optional transaction details.

object (AmountDetails)

Breakdown of the amount. These fields do not affect the actual transaction amount and are for reporting and Level 3 only.

object (Address)
object (Address)
object (CustomFields)
Array of objects (Item) non-empty

Line item details for Level 3 data.

The data will not be checked for accuracy, e.g. if the totals add up correctly.

To qualify for Level 3, the line item amounts must match the transaction amounts.

The new data will replace the old data.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1,
  • "amount": 0.01,
  • "customer": {
    },
  • "transaction_details": {
    },
  • "amount_details": {
    },
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "custom_fields": {
    },
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "auth_amount": 0,
  • "auth_code": "string"
}

Queue

Removes the authorization from the current open batch and places it into the queue. If the authorization is already queued, this will still return a successful response.

Only applicable to credit card authorizations. This is not supported for terminal transactions.

This request requires the Capture permission on the source key.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the authorization to queue.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1
}

Verification

Verifies that a card number, and optionally AVS and/or CVV2 data, is valid.

Only applicable to credit card authorizations. This transaction will not be saved in the gateway.

This request requires the Auth Only permission on the source key.

For Amex cards, if a CVV2 is sent and an Amex processor is available, it will be used, regardless of processor logic. If the only CC processor is a Fiserv (FirstData) platform, the CVV2 might be left out of the verification request sent to the processor, since their platforms do not support CVV2 in all situations.

Authorizations:
BasicAuthentication
Request Body schema: application/json
One of
card
required
string [ 14 .. 16 ] characters ^\d+$

Card number
expiry_month
required
integer [ 1 .. 12 ]

Card expiration month. If using a card token, send any valid month.

expiry_year
required
integer [ 2020 .. 9999 ]

Card expiration year. If using a card token, send any valid year.

avs_address
string <= 255 characters

Billing address for the card.
avs_zip
string <= 50 characters

Billing zip code for the card.

While not required, this field should be populated for fraud prevention and to obtain the best rate for E-commerce credit card transactions.

name
string <= 255 characters

Name on card
object (BaseTransactionDetails)

Additional optional transaction details.

save_card
boolean
Default: false

If set to true and the transaction has been approved, the system will issue a token for future use.

object (TransactionFlags)

These flags provide more details about the transaction. Although they are optional, is recommended they be sent, to ensure optimal approval rates.

cvv2
string [ 3 .. 4 ] characters ^\d+$

Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code on the front of the card. For other card brands, this is the 3 digit code on the back.

While not required, this field should be populated for fraud prevention.

object

Data for 3D-Secure (Verified by Visa, MasterCard SecureCode, Amex SafeKey, Discover ProtectBuy). These values come from a 3rd party 3D-Secure provider.

Note: 3D-Secure is only applicable for e-Commerce merchants. Only 3D-Secure version 2 is supported.

Responses

Request samples

Content type
application/json
Example
{
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "transaction_details": {
    },
  • "save_card": false,
  • "transaction_flags": {
    },
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "cvv2": "stri",
  • "3d_secure": {
    },
  • "card": "stringstringst"
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "avs_result": "string",
  • "avs_result_code": "YYY",
  • "cvv2_result": "string",
  • "cvv2_result_code": "M",
  • "card_type": "string",
  • "last_4": "string",
  • "card_ref": "string",
  • "transaction": {
    }
}

Credit

Refund

Refund a previously settled charge. An error will be returned if the original transaction has not yet settled.

This request requires the Refund permission on the source key for CC transactions, and Check Refund for checks.

ACH transactions can only be refunded after 5 business days have passed since the transaction was processed.

Terminals with connected refunds will behave as matched refunds.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the transaction to refund.

terminal_id
string

The serial number of the terminal. This must match a terminal that is boarded in the gateway.

By default the refund transaction will process on the terminal that the original transaction was processed on. To specify a different terminal, this field can be set.

amount
number [ 0.01 .. 20000000 ]

Amount of original transaction to refund. Omit this field to refund the full amount.

cvv2
string [ 3 .. 4 ] characters ^\d+$

Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code on the front of the card. For other card brands, this is the 3 digit code on the back.

While not required, this field should be populated for fraud prevention.

object (BaseTransactionCustomer)
object (BaseTransactionDetails)

Additional optional transaction details.

object (TransactionFlags)

These flags provide more details about the transaction. Although they are optional, is recommended they be sent, to ensure optimal approval rates.

object (CustomFields)

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1,
  • "terminal_id": "string",
  • "amount": 0.01,
  • "cvv2": "stri",
  • "customer": {
    },
  • "transaction_details": {
    },
  • "transaction_flags": {
    },
  • "custom_fields": {
    }
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "reference_number": 1
}

Credit

Credit money back to a payment method.

A credit can be to one of 3 different types of sources:

  • Credit Card: This requires passing fields with credit card data.
  • Credit Card Magstripe: This requires passing magstripe data from a swiped credit card.
  • Check
  • Source: This includes crediting based on a previous transaction, a stored payment method, or a token.

This feature must be enabled by the ISO/MSP. It requires the Refund permission on the source key for CC transactions, and Check Refund for checks.

Authorizations:
BasicAuthentication
Request Body schema: application/json
One of
card
required
string [ 14 .. 16 ] characters ^\d+$

Card number
expiry_month
required
integer [ 1 .. 12 ]

Card expiration month. If using a card token, send any valid month.

expiry_year
required
integer [ 2020 .. 9999 ]

Card expiration year. If using a card token, send any valid year.

amount
required
number [ 0.01 .. 20000000 ]

Amount to credit.
avs_address
string <= 255 characters

Billing address for the card.
avs_zip
string <= 50 characters

Billing zip code for the card.

While not required, this field should be populated for fraud prevention and to obtain the best rate for E-commerce credit card transactions.

cvv2
string [ 3 .. 4 ] characters ^\d+$

Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code on the front of the card. For other card brands, this is the 3 digit code on the back.

While not required, this field should be populated for fraud prevention.

name
string <= 255 characters

Name on card
object
object

Additional optional transaction details.

object (TransactionFlags)

These flags provide more details about the transaction. Although they are optional, is recommended they be sent, to ensure optimal approval rates.

object (CustomFields)

Responses

Request samples

Content type
application/json
Example
{
  • "avs_address": "string",
  • "avs_zip": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "cvv2": "stri",
  • "name": "string",
  • "card": "stringstringst",
  • "amount": 0.01,
  • "customer": {
    },
  • "transaction_details": {
    },
  • "transaction_flags": {
    },
  • "custom_fields": {
    }
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "reference_number": 1
}

Terminal Credit

Credit money back to a payment method.

This feature must be enabled by the ISO/MSP. It requires the Refund permission on the source key for CC transactions, and Check Refund for checks.

Authorizations:
BasicAuthentication
Request Body schema: application/json
terminal_id
required
string

The serial number of the terminal. This must match a terminal that is boarded in the gateway.

amount
required
number [ 0.01 .. 20000000 ]

Amount to credit.
source
string <= 26 characters (tkn|ref|pm)-[A-Za-z0-9]+

The source to credit. This can be a token, a payment method, or the reference number of a previous transaction. If a reference number is sent, it will only be used to retrieve the account number, but the original transaction will not be affected.

If this field is not sent, the terminal will prompt for a card.

The appropriate prefix must be used:

  • Reference number: ref-
  • Payment method ID: pm-
  • Token: tkn-

By default, a source credit sent without an expiration date will use the expiration date saved with the source. If an expiration date is sent, it will override the saved expiration date.

AVS fields will be automatically populated when using a payment method source unless overridden in the request.

By default, a source credit sent without an expiration date will use the expiration date saved with the source. If an expiration date is sent, it will override the saved expiration date.

Any extra payment method fields sent with a source (e.g. CVV or routing number) will be ignored.

object
object

Additional optional transaction details.

object (CustomFields)

Responses

Request samples

Content type
application/json
{
  • "terminal_id": "string",
  • "amount": 0.01,
  • "source": "string",
  • "customer": {
    },
  • "transaction_details": {
    },
  • "custom_fields": {
    }
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "reference_number": 1
}

Void

Void a previously unsettled charge. An error will be returned if the original transaction has already been settled.

This request requires the Void permission on the source key for CC transactions, and Check Void for checks.

ACH transactions can only be voided until 1am Eastern Time.

FirstData terminal transactions are host capture and can only be voided within 25 minutes of the transaction.

TSYS only supports voids on transactions using US or Canadian cards. International cards must use refunds.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the transaction to void.

object (BaseTransactionCustomer)
object (BaseTransactionDetails)

Additional optional transaction details.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1,
  • "customer": {
    },
  • "transaction_details": {
    }
}

Response samples

Content type
application/json
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string"
}

Reverse

This is a convenience method to completely or partially reverse a previous transaction, regardless of the state which it's currently in. It combines the functionality of the /transactions/adjust, /transactions/void, and /transactions/refund endpoints.

  • If no amount is sent:
    • If the transaction is unsettled, it will be voided.
    • If the transaction is settled, it will be completely refunded.
  • If an amount is sent:
    • If the transaction is unsettled, it will be adjusted by reducing it by the amount passed (amount is the amount to reduce it by, not the new amount). If the amount is the full amount of the authorization, it will be voided.
    • If the transaction is settled, it will be refunded for the amount sent.

ACH transactions can only be voided until 1am Eastern Time the night after the transaction was processed, and can only be refunded after 5 business days have passed since the transaction was processed.

First Data terminal transactions can only be voided within 25 minutes of the transaction. After that point it will be run as a refund/credit regardless if the transaction is settled.

Terminal transactions cannot be adjusted, and will always run as a refund if a different amount is sent regardless if the transaction is settled.

ACH transactions cannot be adjusted, and will return an error if a different amount is sent and they are unsettled.

This endpoint requires that the source key have a pin, and requires the following permissions on the source key:

  • For CC transactions: Charge, Void, and Refund.
  • For checks: Check Void and Check Refund.

TSYS only supports voids/adjusts on transactions using US or Canadian cards. International cards must use refunds.

Terminal full reversals that are processed on a different terminal (by specifying terminal_id) will be processed as a refund, instead of an void.

Terminals with connected refunds will behave as matched refunds.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number of the transaction to reverse.

terminal_id
string

The serial number of the terminal. This must match a terminal that is boarded in the gateway.

By default the reversal transaction will process on the terminal that the original transaction was processed on. To specify a different terminal, this field can be set.

If a different terminal is set, a void will run as a refund.

amount
number [ 0.01 .. 20000000 ]

Amount of original transaction to reverse.

object (BaseTransactionCustomer)
object (BaseTransactionDetails)

Additional optional transaction details.

Responses

Request samples

Content type
application/json
{
  • "reference_number": 1,
  • "terminal_id": "string",
  • "amount": 0.01,
  • "customer": {
    },
  • "transaction_details": {
    }
}

Response samples

Content type
application/json
Example
{
  • "version": "string",
  • "status": "Approved",
  • "status_code": "A",
  • "error_message": "string",
  • "error_code": "string",
  • "error_details": "string",
  • "type": "Void"
}

Surcharge

Get the surcharge settings for a specific payment source

Returns the surcharge that will be automatically applied when processing a transaction using the specified payment source (e.g. a card number).

Authorizations:
BasicAuthentication
Request Body schema: application/json
source_type
required
string
Enum: "card" "tkn" "pm" "ref"
  • card: Card number
  • tkn: Token
  • pm: Payment method ID
  • ref: Reference number
source
required
string <= 16 characters [A-Za-z0-9]+

The source to return the surcharge details for. This can be a card, a token, a payment method ID or the reference number of a previous transaction.

For a source type of card, this does not need to be a full card number. However, the more digits that are sent, the more likely a match will be found.

Responses

Request samples

Content type
application/json
{
  • "source_type": "card",
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "surcharge": {
    },
  • "bin_type": "C",
  • "payment_type": "card"
}

Get the surcharge settings

Authorizations:
BasicAuthentication

Responses

Response samples

Content type
application/json
{
  • "card": {
    },
  • "check": {
    }
}

Batches

Get all batches

Returns a paginated list of all batches.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
status
string
Enum: "open" "closed"

The status of the batch.
integer or string

The earliest date to search. This will be rounded down to the beginning of the day in UTC.

integer or string

The latest date to search. This will be rounded up to the end of the day in UTC.

limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single batch

Get a single batch by batch ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The batch ID.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "opened_at": null,
  • "auto_close_date": null,
  • "closed_at": null,
  • "platform": "north",
  • "charges_sum": 0.01,
  • "charges_count": 1,
  • "credits_sum": 0.01,
  • "credits_count": 1,
  • "transactions_count": 1
}

Get transactions for a batch

Get the transactions in the specified batch.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The batch ID.
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled" "queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"

The transaction status(es) to filter by. Multiple values can be sent, separated by commas.

payment_type
Array of strings
Items Enum: "credit_card" "check"

The transaction payment type(s) to filter by. Multiple values can be sent, separated by commas.

settled_date
string <date>

The settled date in UTC to filter for. This will exclude transactions processed more than 30 days before the specified settlement date, regardless of the date_from query parameter.

date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"

The date event to filter by. This field only has an effect when combined with date_from and date_to filters

integer or string

The earliest date to search. This will be rounded down to the beginning of the day in UTC.

integer or string

The latest date to search. This will be rounded up to the end of the day in UTC.

limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

Get multiple transactions

Returns an array of transactions

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled" "queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"

The transaction status(es) to filter by. Multiple values can be sent, separated by commas.

payment_type
Array of strings
Items Enum: "credit_card" "check"

The transaction payment type(s) to filter by. Multiple values can be sent, separated by commas.

settled_date
string <date>

The settled date in UTC to filter for. This will exclude transactions processed more than 30 days before the specified settlement date, regardless of the date_from query parameter.

date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"

The date event to filter by. This field only has an effect when combined with date_from and date_to filters

integer or string

The earliest date to search. This will be rounded down to the beginning of the day in UTC.

integer or string

The latest date to search. This will be rounded up to the end of the day in UTC.

limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single transaction

Returns a single transaction by reference number

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The transaction ID.

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "settled_date": "2019-08-24",
  • "amount_details": {
    },
  • "transaction_details": {
    },
  • "customer": {
    },
  • "status_details": {
    },
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "custom_fields": {
    },
  • "card_details": {
    }
}

Saved cards

Save a card number

Save a card number for future use. A token will be returned, which can be used later in place of a card number.

This will not verify that the card is valid. It is recommended to instead use a Verification request, and set the save_card property to true. This will run a Verification transaction to verify that the card is valid, and return a token in the response.

Authorizations:
BasicAuthentication
Request Body schema: application/json
One of
card
required
string [ 14 .. 16 ] characters ^\d+$

Card number
expiry_month
required
integer [ 1 .. 12 ]

Card expiration month
expiry_year
required
integer [ 2020 .. 9999 ]

Card expiration year

Responses

Request samples

Content type
application/json
Example
{
  • "card": "stringstringst",
  • "expiry_month": 1,
  • "expiry_year": 2020
}

Response samples

Content type
application/json
{
  • "cardRef": "stringstringstri"
}

Update a saved card

Updates a saved card's expiration by Card Ref

Authorizations:
BasicAuthentication
path Parameters
cardRef
required
string >= 1

The card ref.
Request Body schema: application/json
expiry_month
integer [ 1 .. 12 ]

Card expiration month
expiry_year
integer [ 2020 .. 9999 ]

Card expiration year

Responses

Request samples

Content type
application/json
{
  • "expiry_month": 1,
  • "expiry_year": 2020
}

Response samples

Content type
application/json
{
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "cardRef": "string"
}

Customers

Get multiple customers

Returns an array of customers

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.
active
boolean

The status of the customer.
customer_number
string

The customer_number of the customer.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a customer

Authorizations:
BasicAuthentication
Request Body schema: application/json
identifier
required
string <= 255 characters

Something that identifies the customer, e.g. the customer's name or company.

customer_number
string <= 255 characters

A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <emails> <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
object (Address)
object (Address)
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true,
  • "id": 1
}

Create a customer from a transaction

This will create a new customer using the information from the referenced transaction. A payment method can subsequently be created using the transaction as the source. Any field provided in the body will override the data from the transaction. A new customer will be created even if the transaction is already linked to an existing customer. If the transaction is not already linked to a customer, it will be linked to the newly created customer.

Authorizations:
BasicAuthentication
Request Body schema: application/json
reference_number
required
integer >= 1

Reference number for the transaction.
identifier
string <= 255 characters

Something that identifies the customer, e.g. the customer's name or company.

customer_number
string <= 255 characters

A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <emails> <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
object (Address)
object (Address)
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true,
  • "reference_number": 1
}

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true,
  • "id": 1
}

Get a single customer

Returns a single customers by ID number

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.

Responses

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true,
  • "id": 1
}

Update a customer

Updates a single customer by ID number

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.
Request Body schema: application/json
identifier
string <= 255 characters

Something that identifies the customer, e.g. the customer's name or company.

customer_number
string <= 255 characters

A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <emails> <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
object (Address)
object (Address)
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "customer_number": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "website": "string",
  • "phone": "string",
  • "alternate_phone": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "active": true,
  • "id": 1
}

Delete a customer

Delete a single customer by customer ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.

Responses

Get payment methods for a customer

Returns the payment methods for the specified customer

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a payment method

Creates a payment method for the specified customer.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.
Request Body schema: application/json
One of
card
required
string [ 14 .. 16 ] characters ^\d+$

Card number
expiry_month
required
integer [ 1 .. 12 ]
expiry_year
required
integer [ 2020 .. 9999 ]
avs_address
string <= 255 characters

Billing address for the card.
avs_zip
string <= 50 characters

Billing zip code for the card.

While not required, this field should be populated for fraud prevention and to obtain the best rate for E-commerce credit card transactions.

name
string <= 255 characters

The name on the account.

Responses

Request samples

Content type
application/json
Example
{
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "card": "stringstringst"
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "payment_method_type": "card",
  • "card_type": "Visa",
  • "bin": "string",
  • "bin_details": {
    },
  • "last4": "stri"
}

Get recurring schedules for a customer

Returns the recurring schedules for the specified customer

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a recurring schedule

Creates a recurring schedule for the specified customer.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.
Request Body schema: application/json
title
required
string <= 255 characters
amount
required
number [ 0.01 .. 20000000 ]

Amount to bill.

If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could be different than the amount submitted in this field.

payment_method_id
required
integer >= 1

Payment method ID
frequency
string
Default: "monthly"
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "biannually" "annually"
next_run_date
string <date>

Next date (in EST) that the schedule will run. This must be after today's date. The default is tomorrow in EST.

num_left
integer >= 0
Default: 0

Number of times the schedule has left to bill. Set to 0 for ongoing.

active
boolean
Default: true
receipt_email
string <emails> <= 255 characters

An email address to send a customer receipt to each time the schedule runs.

use_this_source_key
boolean
Default: false

By default, recurring transactions use the Recurring source key. Set this field to true to use the source key that this request authenticated with.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string",
  • "use_this_source_key": false
}

Response samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string",
  • "status": "active",
  • "prev_run_date": "2019-08-24",
  • "transaction_count": 0,
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z"
}

Get transactions for a customer

Get the transactions for the specified customer.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The customer ID.
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled" "queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"

The transaction status(es) to filter by. Multiple values can be sent, separated by commas.

payment_type
Array of strings
Items Enum: "credit_card" "check"

The transaction payment type(s) to filter by. Multiple values can be sent, separated by commas.

settled_date
string <date>

The settled date in UTC to filter for. This will exclude transactions processed more than 30 days before the specified settlement date, regardless of the date_from query parameter.

date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"

The date event to filter by. This field only has an effect when combined with date_from and date_to filters

integer or string

The earliest date to search. This will be rounded down to the beginning of the day in UTC.

integer or string

The latest date to search. This will be rounded up to the end of the day in UTC.

limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payment Methods

Payment Methods are stored credit cards or bank account information.

Get all payment methods

Returns a paginated list of all payment methods.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single payment method

Get a single payment method by payment method ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The payment method ID.

Responses

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "payment_method_type": "card",
  • "card_type": "Visa",
  • "bin": "string",
  • "bin_details": {
    },
  • "last4": "stri"
}

Update a payment method

Updates a payment method by ID number

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The payment method ID.
Request Body schema: application/json
One of
avs_address
string <= 255 characters

Billing address for the card.
avs_zip
string <= 50 characters

Billing zip code for the card.

While not required, this field should be populated for fraud prevention and to obtain the best rate for E-commerce credit card transactions.

name
string <= 255 characters

The name on the account.
expiry_month
integer [ 1 .. 12 ]
expiry_year
integer [ 2020 .. 9999 ]

Responses

Request samples

Content type
application/json
Example
{
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020
}

Response samples

Content type
application/json
Example
{
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avs_address": "string",
  • "avs_zip": "string",
  • "name": "string",
  • "expiry_month": 1,
  • "expiry_year": 2020,
  • "payment_method_type": "card",
  • "card_type": "Visa",
  • "bin": "string",
  • "bin_details": {
    },
  • "last4": "stri"
}

Delete a payment method

Delete a single payment method by payment method ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The payment method ID.

Responses

Get recurring schedules for a payment method

Returns the recurring schedules for the specified payment method

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The payment method ID.

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string",
  • "status": "active",
  • "prev_run_date": "2019-08-24",
  • "transaction_count": 0,
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z"
}

Recurring Schedules

Get all recurring schedules

Returns a paginated list of all recurring schedules.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single recurring schedule

Get a single recurring schedules by ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The recurring schedule ID.

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string",
  • "status": "active",
  • "prev_run_date": "2019-08-24",
  • "transaction_count": 0,
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a recurring schedule

Updates a recurring schedule by ID number

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The recurring schedule ID.
Request Body schema: application/json
title
string <= 255 characters
frequency
string
Default: "monthly"
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "biannually" "annually"
amount
number [ 0.01 .. 20000000 ]

Amount to bill.

If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could be different than the amount submitted in this field.

next_run_date
string <date>

Next date (in EST) that the schedule will run. This must be after today's date. The default is tomorrow in EST.

num_left
integer >= 0
Default: 0

Number of times the schedule has left to bill. Set to 0 for ongoing.

payment_method_id
integer >= 1

Payment method ID
active
boolean
Default: true
receipt_email
string <emails> <= 255 characters

An email address to send a customer receipt to each time the schedule runs.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string"
}

Response samples

Content type
application/json
{
  • "title": "string",
  • "frequency": "daily",
  • "amount": 0.01,
  • "next_run_date": "2019-08-24",
  • "num_left": 0,
  • "payment_method_id": 1,
  • "active": true,
  • "receipt_email": "string",
  • "status": "active",
  • "prev_run_date": "2019-08-24",
  • "transaction_count": 0,
  • "id": 1,
  • "customer_id": 1,
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a recurring schedule

Delete a single recurring schedule by ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The recurring schedule ID.

Responses

Get transactions for a recurring schedule

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The recurring schedule ID.
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled" "queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"

The transaction status(es) to filter by. Multiple values can be sent, separated by commas.

payment_type
Array of strings
Items Enum: "credit_card" "check"

The transaction payment type(s) to filter by. Multiple values can be sent, separated by commas.

settled_date
string <date>

The settled date in UTC to filter for. This will exclude transactions processed more than 30 days before the specified settlement date, regardless of the date_from query parameter.

date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"

The date event to filter by. This field only has an effect when combined with date_from and date_to filters

integer or string

The earliest date to search. This will be rounded down to the beginning of the day in UTC.

integer or string

The latest date to search. This will be rounded up to the end of the day in UTC.

limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Products

Get products

Returns a list of all products.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.
selected_fields
Array of strings

An array of fields to return. Defaults to all available fields.

filter_fields
Array of strings

An array of fields to search, used together with filter_string. Defaults to all selected fields.

filter_string
string

The string to search for in all fields specified in filter_fields.

category_id
Array of integers

An array of category ids to filter products by. Defaults to all categories.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new product

Authorizations:
BasicAuthentication
Request Body schema: application/json
price
required
number [ 0.0001 .. 20000000 ]

The price of the product.
enabled
boolean
Default: true

If the product is currently enabled.
name
string <= 255 characters

The name of the product.
manufacturer
string [ 1 .. 255 ] characters

The name of the manufacturer.
model
string [ 1 .. 255 ] characters

The model name.
sku
string [ 1 .. 255 ] characters

A SKU for the product.
upc
string [ 1 .. 255 ] characters

A UPC for the product.
weight
string [ 1 .. 255 ] characters

The product's weight.
url
string [ 1 .. 255 ] characters

A web url for the product.
description
string [ 1 .. 255 ] characters

The product description.
category_id
integer

The category that this product belongs in.

enabled_from_date
string <date>

The date that this product is available.

ship_weight
string [ 1 .. 255 ] characters

The product's shipping weight.
sale_price
number [ 0.0001 .. 20000000 ]

The sale price of the product.
integer or null

How many of this product still remains in stock. Set to null for unlimited.

min_quantity
integer
Default: 1

Minimum purchase quantity.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "name": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "sku": "string",
  • "upc": "string",
  • "weight": "string",
  • "url": "string",
  • "description": "string",
  • "price": 0.0001,
  • "category_id": 0,
  • "enabled_from_date": "2019-08-24",
  • "ship_weight": "string",
  • "sale_price": 0.0001,
  • "quantity_on_hand": 0,
  • "min_quantity": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "quantity_on_order": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "name": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "sku": "string",
  • "upc": "string",
  • "weight": "string",
  • "url": "string",
  • "description": "string",
  • "price": 0.0001,
  • "category_id": 0,
  • "enabled_from_date": "2019-08-24",
  • "ship_weight": "string",
  • "sale_price": 0.0001,
  • "quantity_on_hand": 0,
  • "min_quantity": 1
}

Get a single product

Returns the requested product.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The product ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "quantity_on_order": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "name": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "sku": "string",
  • "upc": "string",
  • "weight": "string",
  • "url": "string",
  • "description": "string",
  • "price": 0.0001,
  • "category_id": 0,
  • "enabled_from_date": "2019-08-24",
  • "ship_weight": "string",
  • "sale_price": 0.0001,
  • "quantity_on_hand": 0,
  • "min_quantity": 1
}

Update a product

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The product ID.
Request Body schema: application/json
enabled
boolean
Default: true

If the product is currently enabled.
name
string <= 255 characters

The name of the product.
manufacturer
string [ 1 .. 255 ] characters

The name of the manufacturer.
model
string [ 1 .. 255 ] characters

The model name.
sku
string [ 1 .. 255 ] characters

A SKU for the product.
upc
string [ 1 .. 255 ] characters

A UPC for the product.
weight
string [ 1 .. 255 ] characters

The product's weight.
url
string [ 1 .. 255 ] characters

A web url for the product.
description
string [ 1 .. 255 ] characters

The product description.
price
number [ 0.0001 .. 20000000 ]

The price of the product.
category_id
integer

The category that this product belongs in.

enabled_from_date
string <date>

The date that this product is available.

ship_weight
string [ 1 .. 255 ] characters

The product's shipping weight.
sale_price
number [ 0.0001 .. 20000000 ]

The sale price of the product.
integer or null

How many of this product still remains in stock. Set to null for unlimited.

min_quantity
integer
Default: 1

Minimum purchase quantity.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "name": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "sku": "string",
  • "upc": "string",
  • "weight": "string",
  • "url": "string",
  • "description": "string",
  • "price": 0.0001,
  • "category_id": 0,
  • "enabled_from_date": "2019-08-24",
  • "ship_weight": "string",
  • "sale_price": 0.0001,
  • "quantity_on_hand": 0,
  • "min_quantity": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "quantity_on_order": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "enabled": true,
  • "name": "string",
  • "manufacturer": "string",
  • "model": "string",
  • "sku": "string",
  • "upc": "string",
  • "weight": "string",
  • "url": "string",
  • "description": "string",
  • "price": 0.0001,
  • "category_id": 0,
  • "enabled_from_date": "2019-08-24",
  • "ship_weight": "string",
  • "sale_price": 0.0001,
  • "quantity_on_hand": 0,
  • "min_quantity": 1
}

Delete a product

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The product ID.

Responses

Categories

Get all categories

Returns a list of all product categories.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.
parent_id
integer

For subcategories, set this field to the parent category Id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new category

Authorizations:
BasicAuthentication
Request Body schema: application/json
name
required
string

The name of the category.
integer or null
Default: null

For subcategories, this field is the parent category ID.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_id": null
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "parent_id": null
}

Get a single category

Returns the requested category.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The category ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "parent_id": null
}

Update a category

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The category ID.
Request Body schema: application/json
name
string

The name of the category.
integer or null
Default: null

For subcategories, this field is the parent category ID.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_id": null
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "parent_id": null
}

Delete a category

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The category ID.

Responses

Invoices

Get all invoices

Returns a list of invoices.

Authorizations:
BasicAuthentication
query Parameters
order
string
Default: "asc"
Enum: "asc" "desc"

The sort order.
order_by
string
Default: "id"
Enum: "id" "number" "created" "customer" "due" "amount" "status"

The column to order by.
limit
integer [ 1 .. 100 ]
Default: 10

The maximum number of results to return.

offset
integer >= 0

The 0-based offset to start from.
selected_fields
Array of strings

An array of fields to return. Defaults to all available fields.

product_id
integer

A product ID to filter by.
customer_ids
Array of integers

The customer ID(s) to filter by. Multiple values can be sent, separated by commas.

statuses
Array of strings
Items Enum: "canceled" "paid" "partially paid" "sent" "viewed" "authorized" "saved"

The invoice status(es) to filter by. Multiple values can be sent, separated by commas.

amount
number

Filter invoices by amount.
number
string

Filter invoices by invoice number.
due_date
string <date>

Filter invoices by due date.
created_date
string <date>

Filter invoices by created date. (Note: this is not the invoice date).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new invoice

Authorizations:
BasicAuthentication
Request Body schema: application/json
required
Array of objects (NewInvoiceProduct)

A list of products in the invoice.
integer or null
Default: null

The customer ID to send the invoice to. Can be NULL if customer is not saved.

string or null
Default: null

The invoice number. Can be alphanumeric.

If set to NULL, will increment the highest numeric invoice number.

customer_company
string <= 255 characters

The customer name.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

customer_email
string <emails> <= 255 characters

The customer email.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

object

The customer billing info.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

object

The customer shipping info.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

date
string <date>

The invoice date.

Defaults to today's date.
due_date
string <date>

The date the invoice is due.

Defaults to 30 days from invoice date.

note
string

A note to attach to the invoice.
object

Optional discount to apply to the invoice pre tax total.

object

Total amount that is required with first payment. Defaults to full due amount.

object

An optional surcharge to be applied to card or ACH payments. This field will be overwritten if the ISO/MSP sets a mandatory surcharge.

terms
string

Additional terms to attach to the invoice.

action
string
Default: "charge"
Enum: "charge" "authorize"

The action to process the invoice.
send_invoice
boolean
Default: false

Flag to send invoice to immediately send invoice to customer for payment. Set to false to save a draft.

object (InvoiceEmailInfo)

An object containing information related to sending a customer invoice.

Responses

Request samples

Content type
application/json
{
  • "customer_id": null,
  • "number": null,
  • "customer_company": "string",
  • "customer_email": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "note": "string",
  • "discount": {
    },
  • "requirement": {
    },
  • "surcharge": {
    },
  • "terms": "string",
  • "action": "charge",
  • "products": [
    ],
  • "send_invoice": false,
  • "email_info": {
    }
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "invoice_id": 0
}

Get a single invoice

Returns the requested invoice.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "canceled",
  • "to_email": "string",
  • "sub_total_amount": 0,
  • "total_amount": 0,
  • "due_amount": 0,
  • "paid_amount": 0,
  • "tax": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "products": [
    ],
  • "payment_link": "string",
  • "customer_id": null,
  • "number": null,
  • "customer_company": "string",
  • "customer_email": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "note": "string",
  • "discount": {
    },
  • "requirement": {
    },
  • "surcharge": {
    },
  • "terms": "string",
  • "action": "charge"
}

Update an invoice

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.
Request Body schema: application/json
integer or null
Default: null

The customer ID to send the invoice to. Can be NULL if customer is not saved.

string or null
Default: null

The invoice number. Can be alphanumeric.

If set to NULL, will increment the highest numeric invoice number.

customer_company
string <= 255 characters

The customer name.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

customer_email
string <emails> <= 255 characters

The customer email.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

object

The customer billing info.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

object

The customer shipping info.

If invoice is linked to a customer and this field is omitted, it will be populated from the customer.

date
string <date>

The invoice date.

Defaults to today's date.
due_date
string <date>

The date the invoice is due.

Defaults to 30 days from invoice date.

note
string

A note to attach to the invoice.
object

Optional discount to apply to the invoice pre tax total.

object

Total amount that is required with first payment. Defaults to full due amount.

object

An optional surcharge to be applied to card or ACH payments. This field will be overwritten if the ISO/MSP sets a mandatory surcharge.

terms
string

Additional terms to attach to the invoice.

action
string
Default: "charge"
Enum: "charge" "authorize"

The action to process the invoice.

Responses

Request samples

Content type
application/json
{
  • "customer_id": null,
  • "number": null,
  • "customer_company": "string",
  • "customer_email": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "note": "string",
  • "discount": {
    },
  • "requirement": {
    },
  • "surcharge": {
    },
  • "terms": "string",
  • "action": "charge"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "canceled",
  • "to_email": "string",
  • "sub_total_amount": 0,
  • "total_amount": 0,
  • "due_amount": 0,
  • "paid_amount": 0,
  • "tax": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "products": [
    ],
  • "payment_link": "string",
  • "customer_id": null,
  • "number": null,
  • "customer_company": "string",
  • "customer_email": "string",
  • "billing_info": {
    },
  • "shipping_info": {
    },
  • "date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "note": "string",
  • "discount": {
    },
  • "requirement": {
    },
  • "surcharge": {
    },
  • "terms": "string",
  • "action": "charge"
}

Delete an invoice

An invoice can only be deleted before a payment is made.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.

Responses

Send an existing invoice

An invoice can only be sent before a payment is made. Once a payment is made, you must use the Request final payment endpoint.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.
Request Body schema: application/json
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached."

An email body.

The default value will fill in the templated fields. If you supply a body text, it will be sent exactly as supplied without any parsing. However, you can add special escape characters such as \n for new-line

subject
string
Default: "Invoice {invoice_number} from {merchant_company}"

The email subject.

The default value will fill in the templated fields. If you supply a subject text, it will be sent exactly as supplied without any parsing.

to
Array of strings <emails>

A list of email addresses to send to. If not supplied, it will be populated from the customer_email field.

sms_number
Array of strings

A list of numbers to send an sms to.
attach_invoice
boolean
Default: true

Specify if system invoice should be attached to the email.

Responses

Request samples

Content type
application/json
{
  • "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached.",
  • "subject": "Invoice {invoice_number} from {merchant_company}",
  • "to": [
    ],
  • "sms_number": [
    ],
  • "attach_invoice": true
}

Cancel an existing invoice

An invoice can only be canceled once it is sent, but before a payment is made.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.

Responses

Reactivate a canceled invoice

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.
Request Body schema: application/json
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached."

An email body.

The default value will fill in the templated fields. If you supply a body text, it will be sent exactly as supplied without any parsing. However, you can add special escape characters such as \n for new-line

subject
string
Default: "Reactivated Invoice {invoice_number} from {merchant_company}"

The email subject.

The default value will fill in the templated fields. If you supply a subject text, it will be sent exactly as supplied without any parsing.

to
Array of strings <emails>

A list of email addresses to send to. If not supplied, it will be populated from the customer_email field.

sms_number
Array of strings

A list of numbers to send an sms to.
attach_invoice
boolean
Default: true

Specify if system invoice should be attached to the email.

Responses

Request samples

Content type
application/json
{
  • "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached.",
  • "subject": "Reactivated Invoice {invoice_number} from {merchant_company}",
  • "to": [
    ],
  • "sms_number": [
    ],
  • "attach_invoice": true
}

Request final payment for an invoice

Final payment can only be requested for an active invoice that is partially paid.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The invoice ID.
Request Body schema: application/json
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached."

An email body.

The default value will fill in the templated fields. If you supply a body text, it will be sent exactly as supplied without any parsing. However, you can add special escape characters such as \n for new-line

subject
string
Default: "Invoice {invoice_number} from {merchant_company}"

The email subject.

The default value will fill in the templated fields. If you supply a subject text, it will be sent exactly as supplied without any parsing.

to
Array of strings <emails>

A list of email addresses to send to. If not supplied, it will be populated from the customer_email field.

sms_number
Array of strings

A list of numbers to send an sms to.
attach_invoice
boolean
Default: true

Specify if system invoice should be attached to the email.

Responses

Request samples

Content type
application/json
{
  • "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number} attached.",
  • "subject": "Invoice {invoice_number} from {merchant_company}",
  • "to": [
    ],
  • "sms_number": [
    ],
  • "attach_invoice": true
}

Apple Pay Session

Get an Apple Pay session

Use this endpoint to get an Apple Pay session before processing an Apple Pay transaction.

This endpoint requires a public API key (begins with pk_).

The url parameter will be supplied by the Apple Pay JS library when the onvalidatemerchant handler is invoked.

Authorizations:
BasicAuthenticationPublic
Request Body schema: application/json
url
required
string

The URL retrieved from the validationURL property of the data passed to the client-side onvalidatemerchant event.

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{ }

Webhooks

Get webhooks

Returns a list of all webhooks.

Authorizations:
BasicAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new webhook

Authorizations:
BasicAuthentication
Request Body schema: application/json
webhook_url
required
string <= 255 characters ^https://

The url of the webhook.
description
string [ 1 .. 255 ] characters

The webhook description.
active
boolean
Default: true

The status of the webhook

Responses

Request samples

Content type
application/json
{
  • "webhook_url": "string",
  • "description": "string",
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "signature": "string",
  • "webhook_url": "string",
  • "description": "string",
  • "active": true
}

Delete a webhook

Delete a single webhook by ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The webhook ID.

Responses

Get a single webhook

Returns a single webhook by webhook ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The webhook ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "signature": "string",
  • "webhook_url": "string",
  • "description": "string",
  • "active": true
}

Update a webhook

Updates a single webhook by ID.

Authorizations:
BasicAuthentication
path Parameters
id
required
integer >= 1

The webhook ID.
Request Body schema: application/json
webhook_url
string <= 255 characters ^https://

The url of the webhook.
description
string [ 1 .. 255 ] characters

The webhook description.
active
boolean
Default: true

The status of the webhook

Responses

Request samples

Content type
application/json
{
  • "webhook_url": "string",
  • "description": "string",
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "signature": "string",
  • "webhook_url": "string",
  • "description": "string",
  • "active": true
}